# Radio Bar

## Overview


> Image: Illustration of a Radio Bar component.


## When to use this component
- For quick selection within a form. Use only if there are less than 8 options that are simple and straightforward.
- As a filter for related content (e.g. filter messages by “All”, “Read”, and “Unread”).
- Useful to switch between alternate views of the same set of data in the same context. (e.g. list view, grid view, or map view).
- If additional visual affordances and adornments, such as icons, can provide separation between options.

## When to use another component
- If vertical space is not a concern or the options labels are long, use Radio List.
- For binary selections like “on/off”, “yes/no”, “true/false”, consider using a Switch - Toggle.
- Use Tab Bar to change the entire display of different sets of data, as a form of navigation.

```mermaid
graph TD
    accDescr: Decision tree that guides on when to use the RadioBar component or something else
    A(Are users selecting an option in the context of a form?) -- Yes --- B(Are there fewer than 8 options?)
    B -- Yes --- C(Do the options have long labels or you don't need to conserve vertical space?)
    C -- Yes --- D(Radio List)
    C -- No --- E(Radio Bar)
    B -- No --- F(Select or Combo Box)
    A -- No --- G(Do the options work as a form of navigation or switch between completely different content?)
    G -- Yes --- H(Tabs)
    G -- No --- I(Radio Bar)
```

### Check out
- [Radio List][1]
- [Switch][2]
- [Tab Bar][3]
- [Select][4]
- [Combo Box][5]

## Usage

### Inutitive icons
Use icon-only variants when the icons are intuitive and easy to understand.

> Image: Examples of a icon-only Radio Bar with two options. In the first example with heart eyes emojis, the icons are intutive 'List' and 'Rectangle' views. In the second example with grimacing emoji, the icons are a battery and an avatar, two disconnected and unrelated icons.


### Radio Bar as a menu bar
Radio Bar can be used outside the context of a form and behave like a menu `role="menubar"`. When used in this context, ensure the options are straightforward and mutually exclusive.

> Image: Examples of a Radio Bar with two options. In the first example with heart eyes emojis, the options are 'Area chart' and 'Bar chart'. In the second example with grimacing emoji, the options are 'Search and monitoring' and 'Threat detection'.


## Content

### Be concise
Keep option labels short and concise to prevent text wrapping. Use sentence-case capitalization and avoid punctuation and articles (“the”, “an”, “a”).

> Image: Examples of a Radio Bar with two options. In the first example with heart eyes emojis, the options are 'Area chart' and 'Bar chart'. In the second example with grimacing emoji, the options are 'Log analysis area chart.' and 'Real-time list of threats.' and the text wraps onto two lines.


[1]: ./RadioList
[2]: ./Switch
[3]: ./TabBar
[4]: ./Select
[5]: ./ComboBox

## Examples


### Controlled

```typescript
import React, { useState } from 'react';

import RadioBar, { RadioBarChangeHandler } from '@splunk/react-ui/RadioBar';


function Basic() {
    const [value, setValue] = useState(3);

    const handleChange: RadioBarChangeHandler = (e, { value: radioValue }) => {
        setValue(radioValue);
    };

    return (
        <RadioBar onChange={handleChange} value={value} style={{ width: 500 }}>
            <RadioBar.Option value={1} label="one" />
            <RadioBar.Option value={2} label="two" />
            <RadioBar.Option value={3} label="threethreethree" />
            <RadioBar.Option value={4} label="four" />
        </RadioBar>
    );
}

export default Basic;
```



### Uncontrolled

```typescript
import React from 'react';

import RadioBar from '@splunk/react-ui/RadioBar';


function Uncontrolled() {
    return (
        <RadioBar defaultValue={2} style={{ width: 500 }}>
            <RadioBar.Option value={1} label="one" />
            <RadioBar.Option value={2} label="two" />
            <RadioBar.Option value={3} label="threethreethree" />
            <RadioBar.Option value={4} label="four" />
        </RadioBar>
    );
}

export default Uncontrolled;
```



### Error

```typescript
import React from 'react';

import RadioBar from '@splunk/react-ui/RadioBar';


function RadioBarError() {
    return (
        <RadioBar defaultValue={2} style={{ width: 500 }} error>
            <RadioBar.Option value={1} label="one" />
            <RadioBar.Option value={2} label="two" />
            <RadioBar.Option value={3} label="threethreethree" />
            <RadioBar.Option value={4} label="four" />
        </RadioBar>
    );
}

export default RadioBarError;
```



### Disabled

Either the entire RadioBar or individual Options can be disabled using the disabled prop. When set on the RadioBar, this overrides any individual Option disabled states.

```typescript
import React from 'react';

import RadioBar from '@splunk/react-ui/RadioBar';


function Disabled() {
    return (
        <RadioBar defaultValue={2} disabled style={{ width: 500 }}>
            <RadioBar.Option value={1} label="one" />
            <RadioBar.Option value={2} label="two" />
            <RadioBar.Option value={3} label="threethreethree" />
            <RadioBar.Option value={4} label="four" />
        </RadioBar>
    );
}

export default Disabled;
```



### Adornments using `aria-*` attributes

```typescript
import React from 'react';

import styled from 'styled-components';

import ChartArea from '@splunk/react-icons/ChartArea';
import ChartBubble from '@splunk/react-icons/ChartBubble';
import ChartLine from '@splunk/react-icons/ChartLine';
import Plus from '@splunk/react-icons/Plus';
import Chip from '@splunk/react-ui/Chip';
import RadioBar from '@splunk/react-ui/RadioBar';
import { mixins, variables } from '@splunk/themes';

const StyledNewChip = styled(Chip)`
    ${mixins.typography('smallBody', { weight: 'bold' })}
    background-color: ${variables.notificationColorInfoWeak};
    height: calc(${variables.inputHeight} - ${variables.spacingMedium});
`;


function AdornmentAriaExamples() {
    return (
        <RadioBar defaultValue={3} style={{ width: 800 }}>
            <RadioBar.Option value={1} label="Option one" endAdornment={<ChartLine />} />
            <RadioBar.Option value={2} label="Option two" startAdornment={<ChartBubble />} />

            <RadioBar.Option
                value={3}
                label="Option three"
                aria-describedby="new"
                endAdornment={<StyledNewChip id="new">New</StyledNewChip>}
            />

            <RadioBar.Option
                value={4}
                label="Option four"
                startAdornment={<Plus />}
                endAdornment={<ChartArea />}
            />
        </RadioBar>
    );
}

export default AdornmentAriaExamples;
```



### menubar

Radio Bar can be used outside of a form context to behave like a menu bar by setting role="menubar"

```typescript
import React, { useState } from 'react';

import RadioBar, { RadioBarChangeHandler } from '@splunk/react-ui/RadioBar';


function MenuBar() {
    const [value, setValue] = useState('ts');

    const handleChange: RadioBarChangeHandler = (e, { value: radioValue }) => {
        setValue(radioValue);
    };

    return (
        <RadioBar role="menubar" onChange={handleChange} value={value}>
            <RadioBar.Option value="ts" label="Typescript" />
            <RadioBar.Option value="js" label="Javascript" />
        </RadioBar>
    );
}

export default MenuBar;
```




## API


### RadioBar API

RadioBar is a form control that provides the ability to select one option out of a group.

#### Props

| Name | Type | Required | Default | Description |
|------|------|------|------|------|
| children | React.ReactNode | no |  | `children` should be `RadioBar.Option`. |
| defaultValue | string \| number \| boolean | no |  | The default value. Only applicable if this is an uncontrolled component. Otherwise, use the value prop. |
| describedBy | string | no |  | The id of the description. When placed in a ControlGroup, this is automatically set to the ControlGroup's help component. |
| disabled | boolean | no | false | Disable all options in the RadioBar. This will override the disabled prop on any individual Option. |
| elementRef | React.Ref<HTMLDivElement> | no |  | A React ref which is set to the DOM element when the component mounts, and null when it unmounts. |
| error | boolean | no |  | Highlight the field as having an error. The buttons will turn red. |
| inline | boolean | no |  |  |
| labelledBy | string | no |  | The id of the label. When placed in a ControlGroup, this is automatically set to the ControlGroup's label. |
| name | string | no |  | The name is returned with onChange events, which can be used to identify the control when multiple controls share an onChange callback. |
| onChange | RadioBarChangeHandler | no |  | A callback that receives the new value. |
| role | 'radiogroup' \| 'menubar' | no | 'radiogroup' | The role of the RadioBar. The children Options' `role` will be set to `radio` or `menuitemradio` respectively. |
| value | string \| number \| boolean | no |  | The currently selected value. Only applicable if this is a controlled component. |

#### Types

| Name | Type | Description |
|------|------|------|
| RadioBarChangeHandler | (     e: React.MouseEvent<HTMLButtonElement \| HTMLAnchorElement> \| React.KeyboardEvent<HTMLElement>,     data: {         label?: string;         name?: string;         value: any; // eslint-disable-line @typescript-eslint/no-explicit-any     } ) => void |  |



### RadioBar.Option API

#### Props

| Name | Type | Required | Default | Description |
|------|------|------|------|------|
| disabled | boolean | no |  | Add a disabled attribute and prevent clicking. |
| endAdornment | React.ReactNode | no |  | Adornment after the label. |
| label | string | no |  | The text shown on the button. |
| startAdornment | React.ReactNode | no |  | Adornment in front of the label. |
| value | any | yes |  | The value of the `Option`. |